PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / win / vb / insight.exe / BASDOC.TXT < prev next >

Wrap

Text File | 1992-10-22 | 82.2 KB | 1,591 lines

BASIC Insight (tm) Version 2.00 User's Manual Shareware Version (C) Copyright 1992 - All Rights Reserved McKelvy Enterprises 3149 Bradford Place Birmingham, AL 35242 CompuServe ID: 71477,3513 LICENSE The BASIC Insight software and manual are copyrighted, all rights are reserved. You have purchased a license to use this software on one machine at a time. You are authorized to make copies of BASIC Insight for the sole purpose of backing up your software and protecting your investment from loss. Note: This copy of BASIC Insight is being distributed as Shareware. This means that you may copy the disk just as you received it and you may give it to others for their trial use. You are also permitted and encouraged to upload this version to electronic bulletin board services. You may not, however, resell or collect any fee for the distribution of BASIC Insight without the permission of McKelvy Enterprises. (This does not include the normal fees for using bulletin boards.) If you continue to use BASIC Insight after your trial use, you must pay the purchase price as detailed below. WARRANTY This software will perform as described herein only if properly applied. Our liability to you is limited to replacing the software (FOR REGISTERED USERS ONLY). We have no liability to you for any damage or loss (whether special, incidental, or consequential) caused by this software, either directly or indirectly. You agree to the terms of this license by your decision to use this software. SHAREWARE BASIC Insight is copyrighted. It is not a public domain program. It is being distributed as Shareware, which means that unmodified copies of the software and documentation may be freely copied and shared. We ask in return that should you find BASIC Insight to be a useful program, you become a registered user by sending $30.00 to: McKelvy Enterprises 3149 Bradford Place Birmingham, AL 35242 The file ORDER.FRM on the disk can be printed and used as an order form. By becoming a registered user, you get: o The latest version of the software without the introductory Shareware screen. o Free telephone (your Quarter) support for help with problems in running BASIC Insight. In addition, you may make suggestions on how to improve the program. You may also get support by writing to us at the above address (this is the preferred method). o A bound user's manual showing sample code (some with intentional errors) and the output produced by BASIC Insight. o Information on new versions of BASIC Insight as soon as they are available. o The source code for BASIC Insight (available to registered users for an additional fee). The shareware philosophy is to pay smaller amounts for well-crafted and useful software from developers who cannot spend the millions of dollars on packaging and marketing necessary to compete with the large software development companies. You benefit by being able to try (for free) a wider variety of software products to find the ones that best suit your particular purpose. The shareware developer benefits from being able to distribute his work to a wider audience than would be possible through normal channels. In order for Shareware to grow and prosper (with the development of more and better products), it is your responsibility to distribute your shareware programs to others and to become a registered user of those products you like and use. 1.0 Introduction BASIC Insight is a program designed to help with the documentation and debugging of BASIC programs. The program is specifically designed for use with programs developed with Microsoft's QuickBASIC (tm) or Professional Development System (PDS) (tm). It may also be used to process programs written with Visual BASIC, provided that the programs have been saved in text format. BASIC Insight has been tested with programs written in IBM's BASICA and Microsoft's GW-BASIC and worked equally well with these programs. The purpose of BASIC Insight is to provide the system developer with a formatted source listing and variable cross-reference for BASIC programs. The formatted listing will show DO..LOOP and WHILE..WEND ranges, IF..THEN..ELSE..END IF true and false ranges, and the range of each CASE statement in a SELECT CASE group. The listing will also display error messages if program loops are improperly nested. The variable cross-reference will show the name of each variable or BASIC keyword in a subroutine (or the main module) and the line numbers where the variable is referenced. Additionally, a global variable cross-reference is also available. This shows the names of the subroutines which use each variable or BASIC keyword. The program documentation along with its table of contents may be written either to a file or to the printer. In addition to the listing described above, BASIC Insight is also capable of simultaneously producing an indented source listing. This is simply a copy of the input program with all of the DO..LOOP, WHILE..WEND, IF..THEN..ELSE..END IF, and SELECT CASE structures indented for easier reading. The indented source listing is a program file and can be used like any other program file you might create. System Requirements BASIC Insight will work on any IBM-compatible personal computer running MS-DOS or PC-DOS 3.30 (or higher) with at least 512K of available memory. The program may be run from a floppy drive, but a hard drive is recommended, and may be essential, for the variable cross-reference due to the size of temporary files. The program speed is, of course, dependent on processor speed, but does not seem to be dependent on processor type (i.e., 286 vs 386). A program of about 2000 lines can be processed in less than a minute without the cross-reference, and in about two minutes with the cross-reference running on a 20MHz 386 machine. What's New Version 2.00 is a major re-write of BASIC Insight. The features incorporated into the new version are: 1) menu operation (similar to QuickBASIC menus, 2) enhanced command line operation, 3) support for MAK files (lists of files to process) and INCLUDE files, 4) the ability to save and recall certain program configuration information (i.e., page layouts, page headers, etc.), 5) a user definable page header, 6) both local and global variable concordances (cross- references), 7) separation of variables and BASIC keywords, 8) indented source output, 9) documentation table of contents, 10) support for Visual BASIC programs, and 11) mouse support. 2.0 Running BASIC Insight You can run BASIC Insight in either a menu mode or a command line mode. In either case, you start the program by typing BASDOC, followed by any command line options, at the DOS prompt and pressing <Enter>. This assumes either that you are in the directory which contains BASIC Insight or that you have that directory specified in your PATH statement. If this is not the case, you will need to specify the full path to the BASIC Insight executable file (i.e., C:\BASDOC\BASDOC). As stated, a number of the programs options can be specified from the command line using command line options. Command line options are designated by a slash (/), followed by a letter, followed by the option data. The command line option of /G causes the program to bypass the menus, run the analysis of the specified program, and return to the DOS prompt. If the /G option is not specified, then any options entered will be used as the initial values in the menus. In the following descriptions, each section will describe a menu option, and the equivalent command line option (if any) will be specified. In addition, the command line options will be summarized in Appendix A. The four main menu options (File, Options, Run, and Help) are described in Sections 2.1 through 2.4 respectively. In each menu section, the text will be referred to input structures such as an input box, list box, check box, and option box. These input structures and how they are used will be described in Appendix B. In either mode of operation, as BASIC Insight is running, information about the program being analyzed and the format of the output will be displayed on the screen in an information box as shown below: +===========================================================================+ | | | Input File: C:\BASIC\SAMPLE.BAS | | Output to: C:\BASIC\SAMPLE.LST | | MAK File?: No Process INCLUDE Files?: No | | Create formatted source files?: Yes Extension: SRC | | | | Local Concordance: Variable: Yes Keyword:No | | Global Concordance: Variable: Yes Keyword:No | | | | Line Length: 115 Lines per Page: 60 | | Number of Characters to Indent: 3 | | Page Header: | | Date: \D File: \F Page: \P | | Version of BASIC: QB 4.5 | | | | | | | +===========================================================================+ 2.1 File Menu The File Menu (Figure 2.1) allows the user to 1) specify the input file, 2) identify the input file as a list of files to be processed, 3) specify the output device, 4) indicate that indented source files are to be created, 5) read a configuration file, 6) save a configuration file, or 7) exit the program. The File Menu is accessed by pressing <Alt>-F (holding down the Alt key while pressing F) or by placing the mouse cursor over the word file and clicking the left button. Once the menu is displayed, a selection may be made by pressing the highlighted letter, using the cursor keys to highlight the selection and pressing <Enter>, or placing the mouse cursor over the selection and clicking the left mouse button. In Figure 2.1, the highlighted letter for each selection is shown in boldface type. +========================= Figure 2.1 File Menu ======================+ | | | File Options Run Help | | +--------------------+ | | | Input File | | | | MAK File | | | +--------------------+ | | | Output | | | | Indented Source | | | +--------------------+ | | | Read Configuration | | | | Save Configuration | | | +--------------------+ | | | Exit | | | +--------------------+ | | | +======================================================================+ 2.1.1 Input File When the Input File option is selected from the menu, the user is prompted with an input box (shown in Figure 2.2) in which to enter a file specification. The user may enter a complete file name (optionally including a file path), or may enter a file name containing wildcard characters (i.e., asterisk - *, or question mark - ?). If a complete file name is entered, the program checks for the file's existence and notifies the user if the file is not found. If wildcards are used, the user is presented with a list box containing file names (example in Figure 2.3) which match the file specification and the user may then choose a file from the list. If the user selects <Cancel> from the list box, then a message is displayed reminding the user that no file was selected. If the user does not specify a path in the input file description, then the default path for source files is used. This path is specified in the File Paths menu option described in Section 2.2.3. Once the input file has been specified, the name (along with the full path) is shown in the program information box. Command Line Option: /Finput file When specifying the input file from the command line, the input file must be specified, must immediately follow the /F, and Wildcards may not be used. Also, the path for the files is assumed to be the current directory if no path is specified. +============== Figure 2.2 File Specification Input Box =================+ | | | +----------------------------------------------------------+ | | | | | | | Enter a file specification: | | | | +-----------------------------------+ | | | | | *.* | | | | | +-----------------------------------+ | | | | | | | | < OK > | | | | | | | | | | | +----------------------------------------------------------+ | | | +==========================================================================+ +================ Figure 2.3 File List Box ==========================+ | +---------------------------+ | | | +----------------+ | | | | | SAMPLE1.BAS | | | | | | SAMPLE1.EXE ^ | | | | | SAMPLE1.LST * | | | | | SAMPLE1.OBJ # | | | | | SAMPLE2.BAS # | | | | | SAMPLE2.EXE # | | | | | SAMPLE2.LST # | | | | | SAMPLE2.OBJ # | | | | | SAMPLE3.BAS # | | | | | SAMPLE3.EXE # | | | | | SAMPLE3.LST # | | | | | SAMPLE3.OBJ v | | | | | TEST.BAT | | | | | +----------------+ | | | | | | | | < OK > < Cancel > | | | | | | | +---------------------------+ | | | +=======================================================================+ 2.1.2 MAK File This option specifies whether or not the file entered as the input file is in fact a list of files to be processed. The list of files must be in ASCII format with one file per line. On each line, the file name must be the first entry on the line and must be separated from any other information on the line by a space. The status of the option is displayed in the information box, and is shown on the menu by the presence (if activated) or absence (not activated) of a » mark. Command Line Option: /M 2.1.3 Output When the Output option is selected from the menu, an option box (Figure 2.4) is presented which allows the user to select None (for no documentation output), File (for output to a file), or Printer (for output to a print device). If None is selected, no documentation output is produced. This option would be selected if the user only wants to produce an indented source file as described in Section 2.1.4. If File is selected, the user is prompted with an input box in which to enter a file specification. The user may enter a complete file name (optionally including a file path), or may enter a file name containing wildcard characters. If a complete file name is entered, the program checks for the file's existence and notifies the user if the file is found, asking if it should be overwritten. If wildcards are used, the user is presented with a list of files which match the file specification and the user may then choose a file from the list. If the user does not specify a path in the output file description, the default path for source files is used. This path is specified in the File Paths menu option described in Section 2.2.3. The input box and list box for the output file are the same as those for the input files (Figures 2.2 and 2.3). If Printer is selected, the user is presented with a list box (Figure 2.5) containing the print devices LPT1 - LPT4 and COM1 - COM4, and a selection of the print device is made from the list. Once the output device has been specified, the information is displayed in the information box. Command Line Option: /Ooutput When specifying the output device from the command line, the user should either enter a complete file name (including the file path if necessary) or the name of a print device (i.e., LPT1 or COM1). As with the input file, wildcards may not be entered from the command line. If no output device is specified on the command line, then "None" is assumed. +====================== Figure 2.4 Output =============================+ | | | +=================== Output Device Selection ==================+ | | | | | | | | | | | | | | | Output Devices for Documentation File | | | | (*) None ( ) File ( ) Printer | | | | Output to: | | | | | | | | | | | | < Cancel > | | | | | | | +==============================================================+ | | | +========================================================================+ +================ Figure 2.5 Printer List Box =======================+ | +---------------------------+ | | | +----------------+ | | | | | LPT1 | | | | | | LPT2 ^ | | | | | LPT3 * | | | | | LPT4 # | | | | | COM1 # | | | | | COM2 # | | | | | COM3 v | | | | | COM4 | | | | | +----------------+ | | | | | | | | < OK > < Cancel > | | | | | | | +---------------------------+ | | | +=======================================================================+ 2.1.4 Indented Source Listing This option allows the user to generate indented source files. These files are the same as the input program files except that command structures (such as DO loop, IF statements, CASE structures, etc.) are indented by a specified number of spaces. This makes the source code itself easier to read, but does not affect the performance of the program. It can still be edited and compiled like any other program file. When the option is selected, an option box is presented asking if source files are to be created. The user selects either the "Yes" or "No" button in the box. The extension for the source file is specified in the File Paths menu option described in Section 2.2.3. The default file extension is "SRC". Command Line Option: /Sext When specifying from the command line that source files are to be created, the file extension for the files must be specified. 2.1.5 Read Configuration File When this option is selected, information about the analysis to be performed and the layout of the documentation is read in from a file. The information includes whether local and/or global concordances (for variables or keywords) should be generated, the number of spaces to indent structures, the length of the output line, the number of lines per page, the page header, and the default language to use for keyword lookup. The configuration file used in the menu options is always BASDOC.CFG and is found in the path designated in the File Paths menu option (Section 2.2.3). Command Line Option: /Cfilename When specifying the configuration file from the command line, the configuration file may have any file name. It is recommended that the configuration file be placed prior to other format options on the command line, as the information in the file will override any format information already entered. A sample configuration file and a description of how to create a file can be found in Appendix C. 2.1.6 Save Configuration File When this option is selected, information about the analysis to be performed and the layout of the documentation is saved to a file. The information includes whether local and/or global concordances should be generated, the number of spaces to indent structure, the length of the output line, the number of lines per page, the page header, and the default language to use for keyword lookup. The configuration file name used is always BASDOC.CFG, and the file is output to the path designated in the File Paths menu option (Section 2.2.3). 2.1.7 Exit Choosing this option terminates the program and returns the user to the DOS prompt. 2.2 Options Menu The Options Menu (Figure 2.6) allows the user to specify the output page format, the analysis options, and the file paths for various files used by BASIC Insight. The Options Menu is accessed by pressing <Alt>-O (holding down the Alt key while pressing O) or by placing the mouse cursor over the word Options and clicking the left button. Once the menu is displayed, a selection may be made by pressing the highlighted letter, using the cursor keys to highlight the selection and pressing <Enter>, or placing the mouse cursor over the selection and clicking the left mouse button. In Figure 2.6, the highlighted letter for each selection is shown in boldface type. +======================= Figure 2.6 Options Menu =====================+ | | | File Options Run Help | | +--------------------+ | | | Page Layout | | | | Processing Options | | | | File Paths | | | +--------------------+ | | | +======================================================================+ 2.2.1 Page Layout The Page Layout option allows the user to enter format information such as the number of spaces to indent structures, the number of characters per line, the number of lines per page, and the header to be printed at the top of each page. When the Page Layout option is selected, the user is presented with the input box shown in Figure 2.7. The shaded regions indicate edit fields where the user actually enters the information. After filling out the information, the user may select <Accept> to use the entered data, or <Cancel> to return the format settings to their previous values. +================= Figure 2.7 Page Layout Screen =======================+ | | | +=================== Page Layout Options ==========================+ | | | | | | | Number of Spaces to Indent: 4 | | | | | | | | Number of Characters Per Line: 132 | | | | | | | | Number of Lines Per Page: 55 | | | | | | | | Page Header String: | | | | Date: \D Time: \T Filename: \N Subroutine: \S Page | | | | | | | | < Accept > < Cancel > | | | | | | | +==================================================================+ | +=========================================================================+ 2.2.1.1 Spaces to Indent This option specifies the number of spaces to indent each "nest" of DO loops, FOR..NEXT loops, etc. This value controls the appearance of the formatted output. Each statement within the range of a loop is shown with a loop descriptive character and the number of spaces requested by the user in front of it (as shown in the example below). For indented source output files the effect is similar, but there are no line numbers or loop descriptive characters present. Program Segment: DO WHILE condition statement 1 statement 2 statement 3 LOOP Formatted Listing (with 4 spaces selected): 1 DO WHILE condition 2 L statement 1 3 L statement 2 4 L statement 3 5 LOOP In this example, the numbers to the far left are line numbers, and the "L" is the DO loop descriptive character. Indented Source File (with 4 spaces selected): DO WHILE condition statement 1 statement 2 statement 3 LOOP The user can request any number of spaces (up to 10) for the indent function, but recommended values are from 1 to 5. Command Line Option: /Nx When entered from the command line, the user enters the number of space to indent (i.e., /N4). 2.2.1.2 Characters Per Line This option specifies how many characters will be printed before BASIC Insight breaks the program statement into two or more output lines. The length specified will be the number of characters on a line, including the line number, any indentations (see Section 2.2.1.1), and the program statement. The user may input a value of 0, which will tell the program not to split the lines, or any integer value greater than 50. The actual line length to be used will depend on the paper width and print font to be used to print the output file. A value of 132 and a compressed font (17 cpi) for printing works well for most programs. For indented source output, lines are never split and this value is ignored. Command Line Option: /Lxxx When entered from the command line, the user enters the number of characters per line (i.e., /L132). 2.2.1.3 Lines Per Page This option specifies the number of lines to be printed per page when the file is sent to a printer. The program will issue a form feed character each time the "lines per page" counter exceeds the input value. The program will also issue a form feed each time a new subroutine or function is encountered. The lines printed on a page also includes the three-line report header which is printed at the top of each page. While most printers can print up to sixty-six lines per page (some can print more), a value of 55 lines per page seems to work well for most printer setups. Command Line Option: /Pxx From the command line, the user enters the number of lines per page (i.e., /P55). 2.2.1.4 Page Header This option specifies the page header (single line) to be printed at the top of each page of the output report. The page header can be as long as the line length specified in Section 2.2.1.2, and can contain any descriptive text the user wants to include. In addition, the user may include backslash (\) operators in the text to have program-dependent data printed in the header. These operators take the form of \A, where "A" is one of the following five descriptors: D - The date that the report was run. This is pulled from the system date function. T - The time that the run started. This is pulled from the system time function. N - The name of the file being processed. This can be useful when processing a MAK file, as the program will use the names of the files being analyzed to show which routines are part of which file. S - The current subroutine being processed. This is taken from the SUB or FUNCTION statement at the beginning of each routine. For the first routine (which is unnamed), the default name of "Main" is used for all programs except Visual BASIC programs where the default name is "Declarations". P - The current page number. When entering this data in the edit field, up to 132 characters will be accepted as input, but only 60 characters will be displayed at a time. Command Line Option: /Hpage_header_information When entering the page header data from the command line, an underscore (_) must be used to indicate each space in the header string. This is required since the module which processes the command line options looks for spaces to separate the different options. Each underscore will be converted to a space prior to printing the page header. 2.2.2 Processing Options The Processing Options choice allows the user to make choices about the type of concordances (local or global cross-references of variables and/or keywords) to have printed, the language used by the program being analyzed (this is to determine the keyword set to be used), and whether or not to process INCLUDE files. The user is presented with an input panel (Figure 2.8) which contains a series of check boxes, a set of radio buttons for choosing the language, and command buttons for processing the input. After making selections of processing options, the user may select <Accept> to use the selected choices, or <Cancel> to return the processing options to their previous settings. +================= Figure 2.8 Processing Options Screen ===============+ | | | +===================== File Processing Options =====================+ | | | | | | | Local Concordances: Global Concordances: | | | | [X] Variables [X] Variables | | | | [ ] Keywords [ ] Keywords | | | | | | | | [ ] Process INCLUDE Files | | | | | | | | Language to use for Keywords | | | | (*) None ( ) PDS 7.1 ( ) QB 4.5 ( ) VB | | | | | | | | < Accept > < Cancel > | | | | | | | +===================================================================+ | +=========================================================================+ 2.2.2.1 Variable Concordances A variable concordance is a listing of the variables used in a subroutine or a program along with information about where they are used. A local variable concordance may be printed at the end of each subroutine, and lists the variables used in that subroutine and the line numbers on which they appear. This is often useful in discovering typographical errors, or in determining where the value of a variable has been redefined. To select local variable concordance from the input panel, mark the Variables check box under Local Concordances. A global variable concordance may be printed at the end of the program, and lists all the variables used in the program and the subroutines in which they appear. This is useful in helping to determine what effect (if any) changing the value of a variable in one subroutine will have on another subroutine. To select global variable concordance from the input panel, mark the Variables check box under Global Concordances. Command Line Option: /Va From the command line, the letter following the /V determines the type of variable concordance to be printed. For a local concordance, enter L; for a global concordance, enter G; or to have both local and global concordances printed, enter B. 2.2.2.2 Keyword Concordances A keyword concordance is a listing of the keywords used in a subroutine or a program along with information about where they are used. A keyword concordance is most useful in determining the effect of a version change of a language when the operation or syntax of a command might have changed. It is also very useful when porting code from one flavor of BASIC to another (i.e., QuickBASIC to Visual BASIC), or to another language, to determine what commands or functions are required by a program that might not be present in the new language. A local keyword concordance may be printed at the end of each subroutine, and lists the keywords used in that subroutine and the line numbers on which they appear. To select local keyword concordance from the input panel, mark the Keywords check box under Local Concordances. A global keyword concordance may be printed at the end of the program, and lists all the keywords used in the program and the subroutines in which they appear. To select global keyword concordance from the input panel, mark the Keywords check box under Global Concordances. Command Line Option: /Ka From the command line, the letter following the /K determines the type of keyword concordance to be printed. For a local concordance, enter L; for a global concordance, enter G; or to have both local and global concordances printed, enter B. 2.2.2.3 INCLUDE Files INCLUDE files are small segments of BASIC code which provide subroutine declarations, definitions of constants, TYPE declarations, COMMON blocks, and array or variable dimensions. These files are most often used in conjunction with libraries such as interface, graphics, or financial functions, but may also be used if you have certain code pieces that you use in several of your programs. When this option is invoked, BASIC Insight will process INCLUDE files as it encounters them, provided that the file is found. When INCLUDE files are processed, their statements are preceded by "## " prior to any other indent characters. This helps set them off from the rest of your code. To select INCLUDE file processing from the input box, mark the check box for "Process INCLUDE Files". Command Line Option: /I When selecting INCLUDE file processing from the command line, enter the /I option. There are no additional characters required. 2.2.2.4 Programming Language The purpose of selecting the programming language used is to determine the keyword set to be used in the processing of the variable and keyword concordances. If no language is selected, BASIC Insight treats both variables and keywords the same, and processes them as variables in the concordances. Also no keyword concordance is possible. The other reason for specifying the language is that the untitled routine at the beginning of a PDS 7.1 or QB 4.5 program file is considered the "Main" routine. For Visual BASIC, this is considered the declarations area. BASIC Insight uses the language specification to assign the appropriate title to the first routine. To select the language from the input box, mark the space in front of the appropriate language. Command Line Option: /Bn To select the programming language from the command line, the number following the /B option is defined as follows: 1 for PDS 7.1, 2 for QB 4.5, and 3 for Visual BASIC. NOTE: If you are using BASIC Insight with a language other than one of the three that are specifically supported, a custom version of the code tailored for that language can be provided for you (for a small fee) if you will provide us with the keyword list. 2.2.3 File Path Specification The File Path option allows the user to enter path information for files used by BASIC Insight. These are the configuration files, keyword files, help files, and source program files. The default value for the path for configuration, keyword, and help files is the subdirectory where the BASIC Insight executable file is located. The default for the source program files is the current directory. The user may also enter the file extension to be used for indented source output files. The default extension is SRC. When the File Path option is selected, the user is presented with the input box shown in Figure 2.9. The shaded regions indicate edit fields where the user actually enters the information. After filling out the information, the user may select <Accept> to use the entered data, or <Cancel> to return the path settings to their previous values. +=================== Figure 2.9 File Path Input Screen ==================+ | | | +========================== Path Definitions ==========================+ | | | | | | | Path for Configuration File: | | | | C:\BASDOC\ | | | | | | | | Path for Keyword Files: | | | | C:\BASDOC\ | | | | | | | | Path for Help Files: | | | | C:\BASDOC\ | | | | | | | | Path for Source Code Files: | | | | C:\SAMPLES\ | | | | | | | | Extension for Output Source Files: | | | | SRC | | | | | | | | < Accept > < Cancel > | | | | | | | +======================================================================+ | +===========================================================================+ 2.3 Run Menu The Run Menu (Figure 2.10) allows the user to start the processing of the BASIC programs to be analyzed, using the currently defined options. The Run Menu is accessed by pressing <Alt>-R (holding down the Alt key while pressing R) or by placing the mouse cursor over the word Run and clicking the left button. You begin processing the file by pressing the highlighted letter (P), simply pressing <Enter>, or placing the mouse cursor over the selection and clicking the left mouse button. +========================= Figure 2.10 Run Menu =======================+ | | | File Options Run Help | | +-----------------+ | | | Process File(s) | | | +-----------------+ | | | | | | | +======================================================================+ 2.3.1 Process File(s) Selecting this menu item starts the processing of BASIC programs. To show the progress of the analysis, the program keeps a running count of the line number being processed as shown in Figure 2.11. At the end of each routine, the program will perform (if requested) the local variable and keyword concordance. While this is being done, the program displays the variables being processed as shown in Figure 2.12. A similar process occurs at the end of the program if a global variable/keyword concordance has been requested. After the analysis is completed, an alert box is displayed (Figure 2.13) that informs the user of the completion of the run. Pressing <Enter> or clicking the <OK> button will return the user to the menu. Command Line Option: /G When the command option /G is input on the command line, the menu is bypassed, and processing begins immediately using the files and options specified on the command line. When processing is completed, the program returns to the DOS prompt. The main use of this option is to allow the building of a batch file to process several different programs at once. +================= Figure 2.11 Line Count Display =====================+ | | | +----------------------------------------------+ | | | | | | | Processing line number: 50 | | | | | | | | | | | | | | | | | | | | | | | +----------------------------------------------+ | | | +=========================================================================+ +============ Figure 2.12 Variable Processing Display =================+ | | | +----------------------------------------------+ | | | | | | | Processing line number: 183 | | | | | | | | | | | | | | | | | | | +---------+----------------------------------------------+--------+ | | | Printing Variable Cross-Reference | | | | for Subroutine: Main | | | | | | | | lpix | | | | | | | | | | | +-----------------------------------------------------------------+ | | | +=========================================================================+ +=============== Figure 2.13 Analysis Completion Screen ================+ | | | | | +---------------------------------------------+ | | | Processing Completed | | | | | | | | | | | | | | | +---------------------------------------------+ | | | < OK > | | | +---------------------------------------------+ | | | | | +=========================================================================+ 2.4 Help Menu The Help Menu (Figure 2.14) allows the user to access on-line help about the settings of BASIC Insight and about the function of the program. The Help Menu is accessed by pressing <Alt>-H (holding down the Alt key while pressing H) or by placing the mouse cursor over the word Help and clicking the left button. Once the menu is displayed, a selection may be made by pressing the highlighted letter, using the cursor keys to highlight the selection and pressing <Enter>, or placing the mouse cursor over the selection and clicking the left mouse button. In Figure 2.14, the highlighted letter for each selection is shown in boldface type. +======================== Figure 2.14 Help Menu =======================+ | | | File Options Run Help | | +--------------------+ | | | Index | | | | About This Program | | | +--------------------+ | | | | | +======================================================================+ 2.4.1 Index When the Index option is selected, a list box showing the help topics (Figure 2.15) is displayed. The user may then select a help topic by highlighting the topic and selecting the <OK> button, or return to the menu by selecting the <Cancel> button. When a topic is selected, information about the topic is displayed in a window as shown in Figure 2.16. Selecting the <OK> button from the help topic screen returns the user to the help index. +================ Figure 2.15 Help Index Box =========================+ | +---------------------------+ | | | +-----------------+ | | | | | About Box | | | | | | Characters Per ^ | | | | | File Menu * | | | | | File Path Def # | | | | | Help Index # | | | | | Help Menu # | | | | | INCLUDE Files # | | | | | Indented Source # | | | | | Input File # | | | | | Keyword Concord # | | | | | Lines Per Page v | | | | | MAK File | | | | | +-----------------+ | | | | | | | | < OK > < Cancel > | | | | | | | +---------------------------+ | | | +=======================================================================+ +================== Figure 2.16 Help Window ==============================+ | | | +------------------------------------------------------------------------+ | | | Characters Per Line: | | | | This option specifies how many characters will be printed before the | | | | BASIC Insight breaks the program statement into two or more output | | | | lines. The length specified will be the number of characters on a | | | | line, including the line number, any indentations (see Spaces to | | | | Indent), and the program statement. The user may input a value of 0, | | | | which will tell the program not to split the lines, or any integer | | | | value greater than 50. The actual line length to be used will depend | | | | on the paper width and print font to be used to print the output file. | | | | For my own work, I use a value of 132 and a compressed (17 cpi) font | | | | for printing. For indented source output, lines are never split and | | | | this value is ignored. | | | | | | | | | | | | | | | +------------------------------------------------------------------------+ | | | < OK > | | | +------------------------------------------------------------------------+ | | | +============================================================================+ 2.4.2 About This Program This option displays a window (like the help window in Figure 2.16) that contains a general description of the program. Selecting the <OK> button returns the user to the main menu. 2.4.3 Command Line Help Command Line Option: /? When this option is entered on the command line, the program prints out to the screen a listing of the command line options, including a brief description of each. 3.0 Enhancements Future versions of BASIC Insight may be developed and released to enhance the capabilities of the current program. Below is a list of possible program enhancements for later versions. Input from registered users will help determine the priority in which these get implemented. Additional suggestions from users may also be included. Enhanced versions of the program will be available to all registered users for about $10. This covers the cost of postage and of new disks and manuals. Possible enhancements: o Output directed to screen. o Tree structure showing subroutine calls. Appendix A: Command Line Options Summary In the following text, the optional parameters that may be entered on the command line will be described. Each option is preceded by a slash (/), is identified by a single letter option designator (shown in boldface type), and is immediately followed by the required input (shown in italics). In addition to the description of the command, the default values for each option will be listed. /Finput_file This option specifies the BASIC program source file to be processed. The user must enter the complete filename of the program source or MAK file. The user may optionally enter the file path for the file, but if the path is omitted, the current directory will be assumed. Wildcard characters (* or ?) are not permitted in the input file name. Default: None. /M This option indicates that the file specified by the input file option is actually a list of files to be processed. For each file in the list, the path must either be specified in the MAK file, or the file must reside in the current directory. Default: None. /Ooutput This option specifies the output file or device to be used for the documentation output. If a file is to be used, the user must specify a complete file name (wildcards are not allowed), optionally including the file path. If the path is not specified, the current directory is assumed. If a print device is to be used, the user must specify the device name (i.e., LPT1, LPT2, COM1, etc.). Default: No output. /Cconfig_file This option specifies the name of a configuration file to be read. This file (defined in Appendix C) contains page format and file processing options to be used in running BASIC Insight. Keeping these values in a configuration file relieves the user from entering the information for each file to be processed. The user must enter the complete name of the file (no wildcards), and if the path is not specified, the directory containing the file is assumed to be the same one which contains the BASIC Insight executable file (BASDOC.EXE). Default: None. /I This option specifies that INCLUDE files should also be processed. Default: None. /N# This option specifies the number of spaces (up to 10) to indent command structures. Default: 3. /L### This option specifies the number of characters to print on each line. BASIC Insight will break command lines at the end of the number of characters specified in order to make the output fit properly on the page. If a value of 0 is entered, then lines are not broken. For indented source output files, command lines are never broken and this option is ignored. Default: 80. /P## This option specifies the number of lines to be printed on each page of the documentation output. Default: 60. /Hpage_header This option specifies the page header (single line) to be printed at the top of each page of the output report. The page header can be as long as the line length specified above, and can contain any descriptive text the user wants to include. In addition, the user may include backslash (\) operators in the text to have program-dependent data printed in the header. These operators take the form of \A, where "A" is one of the following five descriptors: D - The date that the report was run. This is pulled from the system date function. T - The time that the run started. This is pulled from the system time function. N - The name of the file being processed. This can be useful when processing a MAK file, as the program will use the names of the files being analyzed to show which routines are part of which file. S - The current subroutine being processed. This is taken from the SUB or FUNCTION statement at the beginning of each routine. For the first routine (which is unnamed), the default name of "Main" is used for all programs except Visual BASIC programs where the default name is "Declarations". P - The current page number. When entering the page header data from the command line, an underscore (_) must be used to indicate each space in the header string. This is required since the module which processes the command line options looks for spaces to separate the different options. Each underscore will be converted to a space prior to printing the page header. Default: None. /Va This option specifies the type of variable concordance(s) to be printed. The values of a are as follows: L for local concordance, G for global concordance, or B for both concordances. Default: None. /Ka This option specifies the type of keyword concordance(s) to be printed. The values of a are as follows: L for local concordance, G for global concordance, or B for both concordances. Default: None. /B# This option specifies the programming language used in the source file. This information is used to access a database of keywords so that BASIC Insight can distinguish between variables and keywords when generating the concordances. The values of # for supported versions of BASIC are: 1 for Professional BASIC (PDS), 2 for QuickBASIC, or 3 for Visual BASIC. Any other value entered is ignored, and no language is assumed. Default: 0 (no language). /Sext This option specifies that BASIC Insight should create indented source files using ext as the output file extension. Default: SRC. /G This options tells BASIC Insight to run the analysis using the information specified on the command line (without accessing the menu), and return to DOS upon completion. Default: No additional parameters. Appendix B: Use of Data Input Forms BASIC Insight makes use of several user interface methods to make it easier to move around the program and enter necessary data. These methods are pull-down menus, input boxes, edit fields, check boxes, list boxes, radio button option choices, and command buttons. In this section, techniques for using these methods with either the keyboard or the mouse will be presented. Pull-down Menus BASIC Insight uses a pull-down menu for the main menu of the program. The menu appears as a bar across the top of the screen, and as the main menu options are selected, the sub-menu drops down below the menu bar. To access the main menu options, the user may press the <Alt> key followed by one of the highlighted letters on the menu bar (for example, Alt-F for the File Menu). Once the main menu has been activated, the user may move between main menu options using the left and right cursor keys. To select a sub-menu option using the keyboard, the user may either press the highlighted letter of the menu option, or use the up and down cursor keys to move the light bar to the option then pressing <Enter>. To select a main menu choice using the mouse, the user places the mouse cursor over the option name and clicks the left mouse button. To select a sub-menu option, the user again moves the mouse cursor over the option and clicks the left mouse button. Figure B.1 shows an example of the pull-down menus. +======================= Figure B.1 Pull-Down Menu ===================+ | | | File Options Run Help | | +--------------------+ | | | Input File | | | | MAK File | | | +--------------------+ | | | Output | | | | Indented Source | | | +--------------------+ | | | Read Configuration | | | | Save Configuration | | | +--------------------+ | | | Exit | | | +--------------------+ | | | +======================================================================+ Input Boxes An input box is used to get a single piece of information from the user. Once it has been activated by the program, the user enters the required data in the input area, then presses <Enter> or clicks the mouse on the <OK> command button to accept the entered information and continue the program. Figure B.2 shows an example of an input box. +====================== Figure B.2 Input Box ===========================+ | | | +----------------------------------------------------------+ | | | | | | | Enter a file specification: | | | | +-----------------------------------+ | | | | | *.* | | | | | +-----------------------------------+ | | | | | | | | < OK > | | | | | | | | | | | +----------------------------------------------------------+ | | | +==========================================================================+ Edit Fields Edit fields are used in groups on an input screen to obtain multiple pieces of information from the user, usually about a related subject (i.e., page format options). Each edit field is preceded by a data description and has a highlighted area for actual data input. The user may move between edit fields using the <Tab> and <Shift><Tab> keys, or by clicking on the field with the mouse. In each edit field, the user enters the required information using the keyboard. In BASIC Insight, the screens which use edit fields will also have an <Accept> and a <Cancel> command button. These buttons are described below, and are used to determine whether variables in the program are set to the newly entered values (Accept), or reset to their previous values (Cancel). Using either of these buttons will terminate the particular input screen. Figure B.3 shows an example of a screen with several edit fields. +================= Figure B.3 Edit Field Example =======================+ | | | +=================== Page Layout Options ==========================+ | | | | | | | Number of Spaces to Indent: 4 | | | | | | | | Number of Characters Per Line: 132 | | | | | | | | Number of Lines Per Page: 55 | | | | | | | | Page Header String: | | | | Date: \D Time: \T Filename: \N Subroutine: \S Page | | | | | | | | < Accept > < Cancel > | | | | | | | +==================================================================+ | +=========================================================================+ Check Boxes Check boxes are used on an input screen to indicate options that are either on or off. Each check box consists of a pair of square brackets, [], and a description of the option. If the option is on, an "X" appears in the box between the brackets. To toggle a check box using the keyboard, the user moves the cursor to the check box using the <Tab> or <Shift><Tab> keys, then presses the <Space> bar to toggle the option. Using the mouse, the user toggles the check box value by clicking the left mouse key with the mouse cursor placed over the check box. Like edit field input screens, command buttons will be used on the screen with check boxes to process the options. Figure B.4 shows examples of check boxes and radio buttons (described below). +============= Figure B.4 Check Box and Radio Button Example ===========+ | | | +===================== File Processing Options =====================+ | | | | | | | Local Concordances: Global Concordances: | | | | [X] Variables [X] Variables | | | | [ ] Keywords [ ] Keywords | | | | | | | | [ ] Process INCLUDE Files | | | | | | | | Language to use for Keywords | | | | (*) None ( ) PDS 7.1 ( ) QB 4.5 ( ) VB | | | | | | | | < Accept > < Cancel > | | | | | | | +===================================================================+ | +=========================================================================+ List Boxes A list box is used to allow the user to make a selection among a series of choices, such as a file list. To make a selection using the keyboard, the user moves the cursor to the list area using the <Tab> keys, then uses the up and down cursor and <Page Up> and <Page Down> keys to highlight the selection. The user may then press <Enter> to accept the selection. Using the mouse, the user may click on the selection in the list to highlight it, or may click on the scroll bar (the shaded area to the right of the choices) to move through the list. Clicking on one of the arrows on the scroll bar moves the highlight bar one selection at a time, while clicking on the shaded area above or below the solid block moves the highlight bar one page of selections at a time. Once the selection is highlighted, the user clicks on the <OK> button to accept the selection, or on the <Cancel> button to exit the list box without making a selection. Figure B.5 shows an example of a list box. +================ Figure B.5 List Box Example ========================+ | +---------------------------+ | | | +-----------------+ | | | | | About Box | | | | | | Characters Per ^ | | | | | File Menu * | | | | | File Path Def # | | | | | Help Index # | | | | | Help Menu # | | | | | INCLUDE Files # | | | | | Indented Source # | | | | | Input File # | | | | | Keyword Concord # | | | | | Lines Per Page v | | | | | MAK File | | | | | +-----------------+ | | | | | | | | < OK > < Cancel > | | | | | | | +---------------------------+ | | | +=======================================================================+ Radio Buttons Radio buttons are used to allow the user to choose one of several available choices. Radio buttons consist of a pair of parentheses along with a description of the choice. The currently selected option has a diamond in the parentheses. To select a radio button using the keyboard, the user moves the cursor to the radio button using the <Tab> or <Shift><Tab> keys, then presses the <Space> bar to select the option. Using the mouse, the user selects the radio button by clicking the left mouse key with the mouse cursor placed over the radio button. Figure B.4 shows examples of check boxes and radio buttons. Command Buttons Command buttons are used to initiate an action in the program. When used on an input screen, they are most often used to either accept or cancel the input data entered by the user. Command buttons consist of a command word enclosed in angle brackets, <>. To select a command button with the keyboard, the user must use the <Tab> keys to move the cursor to the command button. The user then presses <Enter> to execute the command. With the mouse, the user just moves the mouse cursor to the command button and clicks the left mouse button. <Accept> and <Cancel> command buttons are shown in Figures B.3 and B.4. Appendix C: Configuration File A configuration file is a text file which contains the values of several program configuration options. The file can be created with any editor which produces ASCII text files. The keywords of the file and the values of the parameters are read in as text strings and must be enclosed in double quotes ("). Each keyword and value combination occupies one line of the file. The keywords and their possible values are listed below. An example of a configuration file is shown in Figure C.1. Keyword Description and Value LOCVAR Local variable concordance desired. Value - 1. GBLVAR Global variable concordance desired. Value - 1. LOCKEY Local keyword concordance desired. Value - 1. GBLKEY Global keyword concordance desired. Value - 1. DEFLNG Default language to use. Value - 1, 2, or 3 as described in Section 2.2.2.4. INDENT The number of spaces to indent structures. Value - 1 through 10. LINLEN The number of character to print per line. Value - 0, or any positive integer over 50. PAGLNG The number of lines to print per page. Value - any positive integer over 10. HEADER The one-line header to be printed at the top of each page. Value - header string as defined in Section 2.2.1.4. +=============== Figure C.1 Sample Configuration File =======================================+ | | | "LOCVAR" "1" | | "GBLVAR" "1" | | "DEFLNG" " 1" | | "INDENT" " 4" | | "LINLEN" " 132" | | "PAGLNG" " 55" | | "HEADER" "Date: \D Time: \T Filename: \N Subroutine: \S Page No: \P" | +==============================================================================================+ Appendix D: Sample Program File DECLARE SUB EndProg () INPUT #1, I ' Select case example SELECT CASE I CASE 1 PRINT "I="; I CASE 2 PRINT "I="; -I CASE 3 PRINT "I="; 0 END SELECT 'If example IF I > 2 THEN PRINT "Yes" ELSE PRINT "No" END IF 'Do loop example J = 1 DO UNTIL J = 5 PRINT J J = J + 1 LOOP 'For example FOR J = 1 TO 10 PRINT -J NEXT J CALL EndProg END SUB EndProg J = 5 * 5 I = 5 ^ .33 PRINT "Five Squared is: "; J PRINT "Cube root of twenty-five is: "; I PRINT "End of Program" END SUB Appendix E: Sample Documentation Output The next several pages show the output resulting from the processing of the sample program shown in Appendix D.Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Main Page No: 1 1 DECLARE SUB EndProg () 2 INPUT #1, I 3 ' Select case example 4 SELECT CASE I 5 CASE 1 6 1 PRINT "I="; I 7 CASE 2 8 2 PRINT "I="; -I 9 CASE 3 10 3 PRINT "I="; 0 11 END SELECT 12 'If example 13 IF I > 2 THEN 14 T PRINT "Yes" 15 ELSE 16 F PRINT "No" 17 END IF 18 'Do loop example 19 J = 1 20 DO UNTIL J = 5 21 L PRINT J 22 L J = J + 1 23 LOOP 24 'For example 25 FOR J = 1 TO 10 26 N PRINT -J 27 NEXT J 28 CALL EndProg 29 END Local Variable Cross Reference for Subroutine: Main EndProg 1 28 I 2 4 6 8 13 J 19 20 21 22 22 25 26 27 Local Keyword Cross Reference for Subroutine: Main CALL 28 CASE 4 5 7 9 DECLARE 1 DO 20 ELSE 15 END 11 17 29 FOR 25 IF 13 17 INPUT 2 LOOP 23 NEXT 27 PRINT 6 8 10 14 16 21 26 SELECT 4 11 Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Main Page No: 2 SUB 1 31 THEN 13 TO 25 UNTIL 20 Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: EndProg Page No: 3 1 SUB EndProg 2 J = 5 * 5 3 I = 5 ^ .33 4 PRINT "Five Squared is: "; J 5 PRINT "Cube root of twenty-five is: "; I 6 PRINT "End of Program" 7 END SUB Local Variable Cross Reference for Subroutine: EndProg EndProg 1 I 3 5 J 2 4 Local Keyword Cross Reference for Subroutine: EndProg END 7 PRINT 4 5 6 SUB 7 Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Page No: 4 Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Page No: 5 Global Variable Cross Reference EndProg Main EndProg I Main EndProg J Main EndProg Date: 09-05-1992 Time: 19:47:14 Filename: D:\BASDOC\SAMPLE.BAS Subroutine: Page No: 6 Table of Contents Subroutine File Page Main D:\BASDOC\SAMPLE.BAS 1 EndProg D:\BASDOC\SAMPLE.BAS 3 Appendix F: Sample Indented Source File DECLARE SUB EndProg () INPUT #1, I ' Select case example SELECT CASE I CASE 1 PRINT "I="; I CASE 2 PRINT "I="; -I CASE 3 PRINT "I="; 0 END SELECT 'If example IF I > 2 THEN PRINT "Yes" ELSE PRINT "No" END IF 'Do loop example J = 1 DO UNTIL J = 5 PRINT J J = J + 1 LOOP 'For example FOR J = 1 TO 10 PRINT -J NEXT J CALL EndProg END SUB EndProg J = 5 * 5 I = 5 ^ .33 PRINT "Five Squared is: "; J PRINT "Cube root of twenty-five is: "; I PRINT "End of Program" END SUB